<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>The Locking Subsystem</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" />
    <link rel="home" href="index.html" title="Getting Started with Berkeley DB Transaction Processing" />
    <link rel="up" href="txnconcurrency.html" title="Chapter 4. Concurrency" />
    <link rel="previous" href="blocking_deadlocks.html" title="Locks, Blocks, and Deadlocks" />
    <link rel="next" href="isolation.html" title="Isolation" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">The Locking Subsystem</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="blocking_deadlocks.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 4. Concurrency</th>
          <td width="20%" align="right"> <a accesskey="n" href="isolation.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="lockingsubsystem"></a>The Locking Subsystem</h2>
          </div>
        </div>
        <div></div>
      </div>
      <p>
            In order to allow concurrent operations, DB provides the locking
            subsystem. This subsystem provides inter- and intra- process
            concurrency mechanisms. It is extensively used by DB concurrent
            applications, but it can also be generally used for non-DB
            resources.
        </p>
      <p>
            This section describes the locking subsystem as it is used to
            protect DB resources. In particular, issues on configuration are
            examined here. For information on using the locking subsystem to
            manage non-DB resources, see the
            <i class="citetitle">Berkeley DB Programmer's Reference Guide</i>.
        </p>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="configuringlock"></a>Configuring the Locking Subsystem</h3>
            </div>
          </div>
          <div></div>
        </div>
        <p>
                You initialize the locking subsystem by specifying
                    
                    <span>
                        <tt class="literal">true</tt> to the 
                            <tt class="methodname">EnvironmentConfig.setInitializeLocking()</tt>
                        method.
                    </span>
            </p>
        <p>
                Before opening your environment, you can configure various
                maximum values for your locking subsystem. Note that these
                limits can only be configured before the environment is
                opened. Also, these methods configure the entire environment,
                not just a specific environment handle.
            </p>
        <p>
                Finally, each bullet below identifies the 
                <tt class="filename">DB_CONFIG</tt> file parameter that can be used
                to specify the specific locking limit. If used, these
                <tt class="filename">DB_CONFIG</tt> file parameters override any
                value that you might specify using the environment handle. 
            </p>
        <p>
                The limits that you can configure are as follows:
            </p>
        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p>
                        The maximum number of lockers
                        supported by the environment. This value is used by
                        the environment when it is opened to estimate the amount
                        of space that it should allocate for various internal
                        data structures. By default, 1,000 lockers are
                        supported.
                    </p>
              <p>
                        To configure this value, use the 
                        
                        <span>
                            <tt class="methodname">EnvironmentConfig.setMaxLockers()</tt>
                         method.
                        </span>
                    </p>
              <p>
                        As an alternative to this method, you can configure this
                        value using the <tt class="filename">DB_CONFIG</tt> file's
                        <tt class="literal">set_lk_max_lockers</tt> parameter.
                    </p>
            </li>
            <li>
              <p>
                        The maximum number of locks supported by the environment.
                        By default, 1,000 locks are supported.
                    </p>
              <p>
                        To configure this value, use the 
                        
                        <span>
                            <tt class="methodname">EnvironmentConfig.setMaxLocks()</tt>
                         method.
                        </span>
                    </p>
              <p>
                        As an alternative to this method, you can configure this
                        value using the <tt class="filename">DB_CONFIG</tt> file's
                        <tt class="literal">set_lk_max_locks</tt> parameter.
                    </p>
            </li>
            <li>
              <p>
                        The maximum number of locked objects supported by the environment.
                        By default, 1,000 objects can be locked.
                    </p>
              <p>
                        To configure this value, use the 
                        
                        <span>
                            <tt class="methodname">EnvironmentConfig.setMaxLockObjects()</tt>
                         method.
                        </span>
                    </p>
              <p>
                        As an alternative to this method, you can configure this
                        value using the <tt class="filename">DB_CONFIG</tt> file's
                        <tt class="literal">set_lk_max_objects</tt> parameter.
                    </p>
            </li>
          </ul>
        </div>
        <p>
                For a definition of lockers, locks, and locked objects, see
                <a href="blocking_deadlocks.html#lockresources">Lock Resources</a>.
            </p>
        <p>
                For example, to configure the maximum number of locks that your
                environment can use:
            </p>
        <pre class="programlisting">package db.txn;
                                                                                                                                     
import com.sleepycat.db.DatabaseException;
import com.sleepycat.db.Environment;
import com.sleepycat.db.EnvironmentConfig;

import java.io.File;
import java.io.FileNotFoundException;
                                                                                                                                     
...
                                                                                                                                     
Environment myEnv = null;
try {
    EnvironmentConfig myEnvConfig = new EnvironmentConfig();
    myEnvConfig.setTransactional(true);
    myEnvConfig.setMaxLocks(5000);

    myEnv = new Environment(new File("/my/env/home"),
                              myEnvConfig);

} catch (DatabaseException de) {
    // Exception handling goes here
} catch (FileNotFoundException fnfe) {
     // Exception handling goes here
}</pre>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="configdeadlkdetect"></a>Configuring Deadlock Detection</h3>
            </div>
          </div>
          <div></div>
        </div>
        <p>
                In order for DB to know that a deadlock has occurred,
                some mechanism must be used to perform deadlock
                detection. There are three ways that deadlock detection can
                occur:
            </p>
        <div class="orderedlist">
          <ol type="1">
            <li>
              <p>
                        Allow DB to internally detect deadlocks as they
                        occur.
                    </p>
              <p>
                        To do this, you use
                            
                            
                            <span><tt class="methodname">EnvironmentConfig.setLockDetectMode()</tt>.</span>
                            This method causes DB to walk its internal lock table 
                            looking for a deadlock whenever a lock request
                            is blocked. This method also identifies how DB decides which lock
                            requests are rejected when deadlocks are detected. For example,
                            DB can decide to reject the lock request for the transaction
                            that has the most number of locks, the least number of locks,
                            holds the oldest lock, holds the most number of write locks, and
                            so forth (see the API reference documentation for a complete
                            list of the lock detection policies).
                    </p>
              <p>
                        You can call this method at any time during your application's
                        lifetime, but typically it is used before you open your environment.
                    </p>
              <p>
                        Note that how you want DB to decide which thread of control should break a deadlock is
                        extremely dependent on the nature of your application. It is not unusual for some performance
                        testing to be required in order to make this determination. That said, a transaction that is
                        holding the maximum number of locks is usually indicative of the transaction that has performed
                        the most amount of work. Frequently you will not want a transaction that has performed a lot of
                        work to abandon its efforts and start all over again. It is not therefore uncommon for
                        application developers to initially select the transaction with the <span class="emphasis"><em>minimum</em></span>
                        number of write locks to break the deadlock.
                    </p>
              <p>
                        Using this mechanism for deadlock detection means
                        that your application will never have to wait on a
                        lock before discovering that a deadlock has
                        occurred. However, walking the lock table every
                        time a lock request is blocked can be expensive
                        from a performance perspective.
                    </p>
            </li>
            <li>
              <p>
                        Use a dedicated thread or external process to perform
                        deadlock detection. Note that this thread must be
                        performing no other database operations beyond deadlock
                        detection.
                    </p>
              <p>
                        To externally perform lock detection, you can use
                        either the
                            
                            
                            <tt class="methodname">Environment.detectDeadlocks()</tt>
                           method, or use the
                           <span><b class="command">db_deadlock</b></span> command line
                           utility. This method (or command) causes DB to walk the
                           lock table looking for deadlocks. 
                    </p>
              <p>
                        Note that like
                            
                            
                            <span><tt class="methodname">EnvironmentConfig.setLockDetectMode()</tt>,</span>
                        you also use this method (or command line utility)
                        to identify which lock requests are rejected in the
                        event that a deadlock is detected.
                    </p>
              <p>
                        Applications that perform deadlock detection in
                        this way typically run deadlock detection between every few
                        seconds and a minute. This means that your
                        application may have to wait to be notified of a
                        deadlock, but you also save the overhead of walking
                        the lock table every time a lock request is blocked.
                    </p>
            </li>
            <li>
              <p>
                        Lock timeouts.
                    </p>
              <p>
                        You can configure your locking subsystem such that
                        it times out any lock that is not released within a
                        specified amount of time. To do this, use the
                            
                            
                            <span><tt class="methodname">EnvironmentConfig.setLockTimeout()</tt></span>
                        method. 
                            Note that lock timeouts are only checked when a
                            lock request is blocked or when deadlock
                            detection is otherwise performed. Therefore, a lock can have timed out and still be held for
                            some length of time until DB has a reason to examine its locking tables.
                    </p>
              <p>
                        Be aware that extremely long-lived transactions, or
                        operations that hold locks for a long time, may be
                        inappropriately timed out before the transaction or
                        operation has a chance to complete. You should
                        therefore use this mechanism only if you know your
                        application will hold locks for very short periods
                        of time.
                    </p>
            </li>
          </ol>
        </div>
        <p>
                For example, to configure your application such that DB
                checks the lock table for deadlocks every time a lock
                request is blocked:
            </p>
        <pre class="programlisting">package db.txn;

import com.sleepycat.db.Environment;
import com.sleepycat.db.EnvironmentConfig;
import com.sleepycat.db.LockDetectMode;

import java.io.File;

...

Environment myEnv = null;
try {
    EnvironmentConfig myEnvConfig = new EnvironmentConfig();
    myEnvConfig.setTransactional(true);
    myEnvConfig.setInitializeCache(true);
    myEnvConfig.setInitializeLocking(true);
    myEnvConfig.setInitializeLogging(true);   

    // Configure db to perform deadlock detection internally, and to
    // choose the transaction that has performed the least amount 
    // of writing to break the deadlock in the event that one 
    // is detected.
    envConfig.setLockDetectMode(LockDetectMode.MINWRITE);

    myEnv = new Environment(new File("/my/env/home"),
                              myEnvConfig);

    // From here, you open your databases, proceed with your 
    // database operations, and respond to deadlocks as 
    // is normal (omitted for brevity).

    ...</pre>
        <p>
        Finally, the following command line call causes
        deadlock detection to be run against the
        environment contained in <tt class="literal">/export/dbenv</tt>. The 
        transaction with the youngest lock is chosen to break the
        deadlock:
    </p>
        <pre class="programlisting">&gt; /usr/local/db_install/bin/db_deadlock -h /export/dbenv -a y</pre>
        <p>
        For more information, see the
        <a href="http://www.oracle.com/technology/documentation/berkeley-db/db/utility/db_deadlock.html" target="_top">
            <tt class="literal">db_deadlock</tt> reference documentation.
        </a>
    </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="deadlockresolve"></a>Resolving Deadlocks</h3>
            </div>
          </div>
          <div></div>
        </div>
        <p>
                When DB determines that a deadlock has occurred, it will
                select a thread of control to resolve the deadlock and then 
                    
                    
                    <span>
                        throws <tt class="literal">DeadlockException</tt> in that
                        thread.
                    </span>
                    
                 If a deadlock is detected, the thread must:
            </p>
        <div class="orderedlist">
          <ol type="1">
            <li>
              <p>
                        Cease all read and write operations.
                    </p>
            </li>
            <li>
              <p>
                        Close all open cursors.
                    </p>
            </li>
            <li>
              <p>
                        Abort the transaction.
                    </p>
            </li>
            <li>
              <p>
                        Optionally retry the operation. If your application
                        retries deadlocked operations, the new attempt must
                        be made using a new transaction.
                    </p>
            </li>
          </ol>
        </div>
        <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
          <h3 class="title">Note</h3>
          <p>
                    If a thread has deadlocked, it may not make any
                    additional database calls using the handle that has
                    deadlocked.
                </p>
        </div>
        <p>
                For example:
            </p>
        <pre class="programlisting">// retry_count is a counter used to identify how many times
// we've retried this operation. To avoid the potential for 
// endless looping, we won't retry more than MAX_DEADLOCK_RETRIES 
// times.

// txn is a transaction handle.
// key and data are DatabaseEntry handles. Their usage is not shown here.
while (retry_count &lt; MAX_DEADLOCK_RETRIES) {
    try {
        txn = myEnv.beginTransaction(null, null);
        myDatabase.put(txn, key, data);
        txn.commit();
        return 0;
    } catch (DeadlockException de) {
        try {
            // Abort the transaction and increment the
            // retry counter
            txn.abort();
            retry_count++;
            if (retry_count &gt;= MAX_DEADLOCK_RETRIES) {
                System.err.println("Exceeded retry limit. Giving up.");
                return -1;
            }
        } catch (DatabaseException ae) {
            System.err.println("txn abort failed: " + ae.toString());
            return -1;    
        }
    } catch (DatabaseException e) {
        try {
            // Abort the transaction.
            txn.abort();
        } catch (DatabaseException ae) {
            System.err.println("txn abort failed: " + ae.toString());
            return -1;    
        }
    }
} </pre>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="blocking_deadlocks.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="txnconcurrency.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="isolation.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Locks, Blocks, and Deadlocks </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Isolation</td>
        </tr>
      </table>
    </div>
  </body>
</html>
